Conducting linguistics research online
A practical introduction using jsPsych and cognition.run
Translations available
Disclaimer: may not be very accurate…
Worksheet overview
Aims
By the end of this worksheet you should be able to:
- program your own experiments in jsPsych
- host the experiment online using cognition.run
- use the participant data for analysis
- apply the basic skills you have learnt for your own purposes
- learn some extra skills such as HTML, javascript, CSS and JSON
Pre-requisites
To complete the aims you will need to:
- follow this worksheet
- ask questions if you are not sure/be able to google
- have a working computer and internet connection
- be patient when things do not work
You do not need to:
- have any programming knowledge
- have high computer literacy
- know anything about jsPsych, cognition.run, html, css or javascript
- be a linguist
Structure
The worksheet will go through the following sections:
Introducing cognition.run
- creating an account
- creating a new experiment
- familiarisation with the interface
Introducing jsPsych
Introducing cognition.run and jsPsych
cognition.run
What is it?
A free and easy way to host your jsPsych experiments.
Why would I use it?
If you do not have access to your own server, or do not want to pay for alternative online server options, this is a nice and simple solution for researchers.
Do I have to spend lots of time learning how it works?
Not really, once you learn how to use jsPsych the interface is really good for beginners to navigate and use.
The free account will allow you to:
- run your jsPsych experiments online
- code and preview your experiment
- access your data as a csv file
- collect a maximum of 80 participants per experiment
- learn the basics and complete this worksheet
It will not be suitable if you:
- need to collect a large amount of data from lots of participants
- collect data that would not be usable in csv format (e.g. audio recordings from participants)
- have stimuli that are very large in size (>2 MB, e.g. videos)
- are looking to host your experiments on your own server
- generally have more complex experimental designs
Setting up an account
Go to https://www.cognition.run/ and click on the
create an accountbutton.Register for a free account by filling in the form.
You will then see a dashboard, where you can see your experiments. Click on the
+ New taskbutton to create a new experiment.Where it says
task nametype the name demo (you can choose a different name if you want, but this is the name that we will use). If you click on theShow advanced configurationbutton to see additional settings, which may be relevant depending on your ethics application (e.g. data storage location, IP address logging). Click theSavebutton to create the experiment.Now you will see the experiment’s dashboard. There are several options on this page which we will cover later, but for now we need to click on the
Source codebutton.On this page you can start writing your code that makes your experiment. Before we start writing our code we will need to know how jsPsych works, which will be covered in the next section. We will return to the cognition.run interface too and see how to interact with it in more detail.
Things might look different
The screenshots above
might look different if you are reading this worksheet at a later date.
This is because websites change, especially ones that are constantly
developing, which also means the cost of using the service might also
change.
jsPsych
What is it?
A free and open source library that
allows users to create and run experiments online. It relies on
javascript, a programming language that most websites use, to
implement plugins that can be used to make your
experiments.
See:
de Leeuw, J. R. (2015). jsPsych: A JavaScript library for creating behavioral experiments in a web browser. Behavior Research Methods, 47(1), 1-12. doi:10.3758/s13428-014-0458-y.
Why should I use it?
It is an extremely
adaptable and easy to use, with a growing community of users, support
and contributors, making it more accessible for everybody to conduct
research online. It is also free and open source.
Do I have to spend lots of time learning how to use
it?
Probably. There is definitely a learning curve, which
will take time to get around, but you learn lots of skills along the
way. The more you learn, the more you can do. However, if you want to
learn the basics you do not need too long to get a working experiment
programmed and available to participants.
Should I be worried if I do not know what javascript
is?
No. The great thing about jsPsych is that much of the
hard work is already done by others, which means you can get by without
worrying about the really complex stuff.
Versions of jsPsych
You might have noticed that
jsPsych has different versions, e.g. 7.3.1, 6.3.0. This is somewhat
confusing at first as you would hope that there would be no major
differences in which version you are using, or that you would just
choose the latest version. However, there are some important differences
between the versions that can affect whether your script will work.
These are largely based on whether you are using version 6.x.x or
7.x.x
In this tutorial we will be using version
7.3.1
You can see an outline of the differences at
https://www.jspsych.org/7.3/support/migration-v7/
Always
try to write somewhere in your script which version of jsPsych you are
working with.
Running experiments
In order to run your experiments, you have write code that will tell jsPsych what you want it to do. This requires you to speak the same way as jsPsych, so that your instructions can be interpreted properly.
Imagine you have to guide somebody from point A to point B on a map, you will have to learn how to give basic instructions like turn left, stop, continue, this is what your code will have to do (but in the context of a linguistics experiment, so more like show this stimuli, collect this input, measure the time it takes to press this button).
Using cognition.run with jsPsych
To run your experiment, you will need somewhere to write your code.
We will therefore return to cognition.run.
The image below outlines which parts of the interface can be used for different purposes. For now, we will focus on 1 and 2 of the interface (writing code and previewing how it looks), with 3 and 4 being explained in more detail later.
0. Commenting your code
Before you start writing proper code that does things, it is important to remember that it is not just the computer who will interpret you write… you and other human brains need to as well.
To make it easier for humans, you can add comments to your code.
Comments don’t do anything to your actual code, but add information to make it easier to understand and interpret. Imagine talking to somebody in a language that you both know, but there is somebody else in the group who does not speak that language, so you might offer a simplified translation to that person, so that they know what is happening. This is sort of similar to what comments do.
You can write a comment in the code section of the cognition.run interface in the following way:
/* This is a comment */These can be as long as you want, but must have /* at
the start, and */ at the end.
Let’s try writing a useful comment in our script, where we say:
- the title of the experiment
- what version of jsPsych we are using
- when we wrote the code [today]
- who is the author of the code [your name]
/*
Title: My first experiment
jsPsych version: 7.3.1
date: [today]
author: [your name]
*/1. Initiating jsPsych
Now we can start writing actual code that will allow us to use jsPsych properly.
In order for your experiment to work, the first line of code in your script should be:
var jsPsych = initJsPsych();Notice that this is not a comment and has a specific structure, or
syntax, which is shown by the colour highlighting of the text.
We can deconstruct this to understand each part of the
code:
varthis indicates that we want to create a variable, which we can use in our experiment.
Notice that it is in a different colour to the rest of the text, this is because it is a keyword that javascript understands to be important, i.e. that you want to create a variable.jsPsychthis is the name of our variable, in theory you can name variables anything that you want.=this is an operator it is used to assign a value to a variable, in this case whatever is on the right of the equals sign will be assigned to our jsPsych variable.initJsPsych()this is a function specifically made for jsPsych experiments, it allows us to initiate an experiment, without this function we would not be able to do anything. Think of it as turning on the power button, nothing will happen until you have this function stored as a variable.;this is a semi-colon, it is an important part of your code as it will allow the script to know that your specific bit of code (or statement) is finished and you can move on to your next one.
What is a variable?
See this
page for more information on what var means.
Choosing a name for your variable
When naming your
variable you should follow these rules:
never include spaces (use_underscores_instead)
never begin with a number
never use a special javascript name (e.g. ‘var’ is not a good name for
your variable)
always make them unique to other variables
always make them memorable
always be aware of upper and lower case (‘myVariable’ will be distinct
from ‘myvariable’)
What goes inside the
brackets?
When you see brackets for a function, there are
normally some additional parameters that you can set, to see what these
are you can always refer to the official jsPsych
documentation, for now we will keep our experiment to the default
settings, so we do not need to add anything inside the
brackets.
Important differences between cognition.run and normal jsPsych
experiments
Your experiment in cognition.run will look a
but different from other JsPsysch experiments, e.g. the ones you might
see that were hosted on private servers. This is because cognition.run
does some things automatically, so you do not need to worry about adding
specific code.
One of the main differences is that all of the
standard JsPsych plugins are automatically loaded for you. We will
discuss this later in the worksheet, but if you have used JsPsych
before, or are copying code from a non cognition.run experiment you
might need to be aware of this.
Essentially, the code you have
in your cognition.run experiment will all be javascript, whereas a
typical JsPsych experiment will be a html file, with the javascript
embedded within that file.